docs(readme): fix broken links and rewrite for clarity, SEO and AI answer engines - #94
Open
KrilinZ wants to merge 3 commits into
Open
docs(readme): fix broken links and rewrite for clarity, SEO and AI answer engines#94KrilinZ wants to merge 3 commits into
KrilinZ wants to merge 3 commits into
Conversation
- Fix broken links: breatheco.de badge (404) -> live asset page; Gitpod badge pointed to a repo that does not exist. - Fix 'learnpack download' command: the package slug is bootstrap-exercises, not the repo name. - Fix 'small React application' -> this tutorial is HTML and CSS. - Add an opening summary, 'What will you build', prerequisites, a grading section, common mistakes and an expanded FAQ. - Move title, badges, metadata, install steps, exercise layout and contributors inside <!-- hide --> so 4geeks.com does not duplicate what the platform already renders. - Use /blob/HEAD/ for the language link so it works on repos whose default branch is main. - No markdown tables: the 4geeks.com renderer does not support them.
All three images already exist in .learn/assets, so nothing new is uploaded. They sit in the published part of the file: markdown images survive the 4geeks.com renderer (verified: an asset with 4 markdown images produces 4 <img> tags in its rendered html). Each one carries a long descriptive alt: it is the only part of an image a screen reader or a language model can read.
An image placed between two list items splits the list in markdown, so the numbering restarted at 1 halfway through 'What will you learn' and 'What will you build'. The images now sit after each list is finished. Verified on the rendered output: 3 <ol> blocks with 5, 8 and 3 items, which is what the source says.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrite of the root README for clarity, search engines and AI answer engines. Same tutorial, no content removed — everything that was there is either still visible or moved inside
<!-- hide -->.Broken things this fixes
breatheco.debadge link4geeks.com. This one is replicated across many exercise repos.4GeeksAcademy/bootstrap-exercises.git, a repo that does not exist.learnpack downloadcommandbootstrap-exercises, so copy-pasting the command failed./blob/master/. Now/blob/HEAD/, which also works on the repos whose default branch ismain.What was added
👀 What will you build?(the 8 real exercises),🎓 What do you need before starting?,✅ How does the automatic grading work?,💡 What mistakes should you avoid?, and an expanded FAQ. All of it written from the repo's own content — the grid facts come from03-Bootstrap-Grid, the duration and difficulty fromlearn.json.What moved inside
<!-- hide -->Title, badges, metadata, related tutorials, install steps, exercise file layout and contributors. The reason:
4geeks.comalready renders its ownh1and its own stats (skill level, duration) from the database, so repeating them in the body shows up twice and can drift out of sync.Two notes
4geeks.comrenderer has no table extension — a markdown table shows up there as raw pipes. Lists are used instead. (This PR body has tables, but that's GitHub-only.)LICENSE.mdreserves all rights and forbids redistribution, so the wording is "costs nothing to access, the code you write is yours" with a link to the licence.All 22 links in the file were checked and return 200. Happy to adjust tone, wording or structure — and if the direction looks right, the same treatment can be applied to the other exercise repos.